home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 April: Mac OS SDK / Dev.CD Apr 99 SDK1.toast / Development Kits / Interfaces&Libraries / Universal / Interfaces / CIncludes / JManager.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  32.1 KB  |  1,006 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        JManager.h
  3.  
  4.      Contains:    Routines that can be used to invoke the Java Virtual Machine in MRJ 
  5.  
  6.      Version:    Technology:    MRJ 2.1
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1996-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __JMANAGER__
  18. #define __JMANAGER__
  19.  
  20. /*
  21.  *  Note:    If you want to use any JManger routines which use JNI or JRI functionality,
  22.  *             you must #include <jni.h> or <jri.h> before this file.
  23.  *
  24.  */
  25. #ifndef __CONDITIONALMACROS__
  26. #include <ConditionalMacros.h>
  27. #endif
  28. #ifndef __MACTYPES__
  29. #include <MacTypes.h>
  30. #endif
  31. #ifndef __FILES__
  32. #include <Files.h>
  33. #endif
  34. #ifndef __DRAG__
  35. #include <Drag.h>
  36. #endif
  37. #ifndef __QUICKDRAW__
  38. #include <Quickdraw.h>
  39. #endif
  40. #ifndef __MENUS__
  41. #include <Menus.h>
  42. #endif
  43. #ifndef __TEXTCOMMON__
  44. #include <TextCommon.h>
  45. #endif
  46.  
  47.  
  48.  
  49. #if PRAGMA_ONCE
  50. #pragma once
  51. #endif
  52.  
  53. #ifdef __cplusplus
  54. extern "C" {
  55. #endif
  56.  
  57. #if PRAGMA_IMPORT
  58. #pragma import on
  59. #endif
  60.  
  61. #if PRAGMA_STRUCT_ALIGN
  62.     #pragma options align=mac68k
  63. #elif PRAGMA_STRUCT_PACKPUSH
  64.     #pragma pack(push, 2)
  65. #elif PRAGMA_STRUCT_PACK
  66.     #pragma pack(2)
  67. #endif
  68.  
  69. #if PRAGMA_ENUM_ALWAYSINT
  70.     #pragma enumsalwaysint on
  71. #elif PRAGMA_ENUM_OPTIONS
  72.     #pragma option enum=int
  73. #elif PRAGMA_ENUM_PACK
  74.     #if __option(pack_enums)
  75.         #define PRAGMA_ENUM_PACK__JMANAGER__
  76.     #endif
  77.     #pragma options(!pack_enums)
  78. #endif
  79.  
  80.  
  81.  
  82. enum {
  83.     kJMVersion                    = 0x11000003,                    /* using Sun's 1.1 APIs, our current APIs. */
  84.     kDefaultJMTime                = 0x00000400                    /* how much time to give the JM library on "empty" events, in milliseconds. */
  85. };
  86.  
  87.  
  88. enum {
  89.     kJMVersionError                = -60000L,
  90.     kJMExceptionOccurred        = -60001L,
  91.     kJMBadClassPathError        = -60002L
  92. };
  93.  
  94. /*
  95.  *    Private data structures
  96.  *
  97.  *    JMClientData        - enough bits to reliably store a pointer to arbitrary, client-specific data. 
  98.  *    JMSessionRef        - references the entire java runtime 
  99.  *    JMTextRef            - a Text string, length, and encoding 
  100.  *    JMTextEncoding        - which encoding to use when converting in and out of Java strings.
  101.  *    JMFrameRef            - a java frame 
  102.  *    JMAWTContextRef     - a context for the AWT to request frames, process events 
  103.  *    JMAppletLocatorRef    - a device for locating, fetching, and parsing URLs that may contain applets 
  104.  *    JMAppletViewerRef    - an object that displays applets in a Frame 
  105.  */
  106. typedef void *                            JMClientData;
  107. typedef struct OpaqueJMSessionRef*         JMSessionRef;
  108. typedef struct OpaqueJMFrameRef*         JMFrameRef;
  109. typedef struct OpaqueJMTextRef*         JMTextRef;
  110. typedef struct OpaqueJMAWTContextRef*     JMAWTContextRef;
  111. typedef struct OpaqueJMAppletLocatorRef*  JMAppletLocatorRef;
  112. typedef struct OpaqueJMAppletViewerRef*  JMAppletViewerRef;
  113. typedef TextEncoding                     JMTextEncoding;
  114.  
  115. /*
  116.  * The runtime requires certain callbacks be used to communicate between
  117.  * session events and the embedding application.
  118.  *
  119.  * In general, you can pass nil as a callback and a "good" default will be used.
  120.  *
  121.  *    JMConsoleProcPtr          - redirect stderr or stdout - the message is delivered in the encoding specified when
  122.  *                                you created the session, or possibly binary data.
  123.  *    JMConsoleReadProcPtr     - take input from the user from a console or file.  The input is expected to 
  124.  *                                be in the encoding specified when you opened the session.
  125.  *    JMExitProcPtr              - called via System.exit(int), return "true" to kill the current thread,
  126.  *                                false, to cause a 'QUIT' AppleEvent to be sent to the current process,
  127.  *                                or just tear down the runtime and exit to shell immediately
  128.  * JMLowMemoryProcPtr          - This callback is available to notify the embedding application that
  129.  *                                a low memory situation has occurred so it can attempt to recover appropriately.
  130.  * JMAuthenicateURLProcPtr  - prompt the user for autentication based on the URL.  If you pass
  131.  *                                nil, JManager will prompt the user.  Return false if the user pressed cancel.
  132.  */
  133. typedef CALLBACK_API_C( void , JMConsoleProcPtr )(JMSessionRef session, const void *message, UInt32 messageLengthInBytes);
  134. typedef CALLBACK_API_C( SInt32 , JMConsoleReadProcPtr )(JMSessionRef session, void *buffer, SInt32 maxBufferLength);
  135. typedef CALLBACK_API_C( Boolean , JMExitProcPtr )(JMSessionRef session, SInt32 status);
  136. typedef CALLBACK_API_C( Boolean , JMAuthenticateURLProcPtr )(JMSessionRef session, const char *url, const char *realm, char userName[255], char password[255])/*  into C string parameters  */;
  137. typedef CALLBACK_API_C( void , JMLowMemoryProcPtr )(JMSessionRef session);
  138.  
  139. struct JMSessionCallbacks {
  140.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  141.     JMConsoleProcPtr                 fStandardOutput;            /* JM will route "stdout" to this function. */
  142.     JMConsoleProcPtr                 fStandardError;                /* JM will route "stderr" to this function. */
  143.     JMConsoleReadProcPtr             fStandardIn;                /* read from console - can be nil for default behavior (no console IO) */
  144.     JMExitProcPtr                     fExitProc;                    /* handle System.exit(int) requests */
  145.     JMAuthenticateURLProcPtr         fAuthenticateProc;            /* present basic authentication dialog */
  146.     JMLowMemoryProcPtr                 fLowMemProc;                /* Low Memory notification Proc */
  147. };
  148. typedef struct JMSessionCallbacks        JMSessionCallbacks;
  149.  
  150. enum JMVerifierOptions {
  151.     eDontCheckCode                = 0,
  152.     eCheckRemoteCode            = 1,
  153.     eCheckAllCode                = 2
  154. };
  155. typedef enum JMVerifierOptions JMVerifierOptions;
  156.  
  157.  
  158. /*
  159.  * JMRuntimeOptions is a mask that allows you to specify certain attributes
  160.  * for the runtime. Bitwise or the fields together, or use one of the "premade" entries.
  161.  * eJManager2Defaults is the factory default, and best bet to use.
  162.  */
  163.  
  164. enum JMRuntimeOptions {
  165.     eJManager2Defaults            = 0,
  166.     eUseAppHeapOnly                = (1 << 0),
  167.     eDisableJITC                = (1 << 1),
  168.     eEnableDebugger                = (1 << 2),
  169.     eDisableInternetConfig        = (1 << 3),
  170.     eInhibitClassUnloading        = (1 << 4),
  171.     eEnableProfiling            = (1 << 5),
  172.     eJManager1Compatible        = (eDisableInternetConfig | eInhibitClassUnloading)
  173. };
  174. typedef enum JMRuntimeOptions JMRuntimeOptions;
  175.  
  176.  
  177.  
  178.  
  179. /*
  180.  * Returns the version of the currently installed JManager library.
  181.  * Compare to kJMVersion.  This is the only call that doesn't
  182.  * require a session, or a reference to something that references
  183.  * a session.
  184.  */
  185. EXTERN_API_C( unsigned long )
  186. JMGetVersion                    (void);
  187.  
  188. /*
  189.  * JMOpenSession creates a new Java Runtime.  Note that JManger 2.0 doesn't set 
  190.  * security options at the time of runtime instantiation.  AppletViewer Objecs have
  191.  * seperate security attributes bound to them, and the verifier is availiable elsewhere
  192.  * as well.  The client data parameter lets a client associate an arbitgrary tagged pointer
  193.  * with the seession.
  194.  * When you create the session, you must specify the desired Text Encoding to use for
  195.  * console IO.  Usually, its OK to use "kTextEncodingMacRoman".  See TextCommon.h for the list.
  196.  */
  197. EXTERN_API_C( OSStatus )
  198. JMOpenSession                    (JMSessionRef *            session,
  199.                                  JMRuntimeOptions         runtimeOptions,
  200.                                  JMVerifierOptions         verifyMode,
  201.                                  const JMSessionCallbacks * callbacks,
  202.                                  JMTextEncoding         desiredEncoding,
  203.                                  JMClientData             data);
  204.  
  205. EXTERN_API_C( OSStatus )
  206. JMCloseSession                    (JMSessionRef             session);
  207.  
  208.  
  209. /*
  210.  * Client data getter/setter functions.
  211.  */
  212. EXTERN_API_C( OSStatus )
  213. JMGetSessionData                (JMSessionRef             session,
  214.                                  JMClientData *            data);
  215.  
  216. EXTERN_API_C( OSStatus )
  217. JMSetSessionData                (JMSessionRef             session,
  218.                                  JMClientData             data);
  219.  
  220.  
  221. /*
  222.  * Prepend the target of the FSSpec to the class path.
  223.  * If a file, .zip or other known archive file - not a .class file
  224.  */
  225. EXTERN_API_C( OSStatus )
  226. JMAddToClassPath                (JMSessionRef             session,
  227.                                  const FSSpec *            spec);
  228.  
  229.  
  230. /*
  231.  * Utility returns (client owned) null terminated handle containing "file://xxxx", or nil if fnfErr
  232.  */
  233. EXTERN_API_C( Handle )
  234. JMFSSToURL                        (JMSessionRef             session,
  235.                                  const FSSpec *            spec);
  236.  
  237.  
  238. /*
  239.  * Turns "file:///disk/file" into an FSSpec.  other handlers return paramErr
  240.  */
  241. EXTERN_API_C( OSStatus )
  242. JMURLToFSS                        (JMSessionRef             session,
  243.                                  JMTextRef                 urlString,
  244.                                  FSSpec *                spec);
  245.  
  246.  
  247. /*
  248.  * JMIdle gives time to all Java threads. Giving more time makes Java programs run faster,
  249.  * but can reduce overall system responsiveness. JMIdle will return sooner if low-level (user)
  250.  * events appear in the event queue.
  251.  */
  252. EXTERN_API_C( OSStatus )
  253. JMIdle                            (JMSessionRef             session,
  254.                                  UInt32                 jmTimeMillis);
  255.  
  256.  
  257. /*
  258.  * JMGetCurrenvEnv gives access to the underlying JRI interface, if available.
  259.  * This gives the client more control over the underlying Java runtime, without
  260.  * exposing the implementation too much.
  261.  * NOTE: JRI is deprecated; please upgrade your code to work with JNI instead.
  262.  */
  263. #ifdef JRI_H
  264. EXTERN_API_C( JRIRuntimeInstance *)
  265. JMGetJRIRuntimeInstance            (JMSessionRef             session);
  266.  
  267. EXTERN_API_C( JRIEnv *)
  268. JMGetCurrentJRIEnv                (JMSessionRef             session);
  269.  
  270. #endif  /* defined(JRI_H) */
  271.  
  272. /*
  273.  * JNI is to be preferred.
  274.  */
  275. #ifdef JNI_H
  276. EXTERN_API_C( JNIEnv *)
  277. JMGetCurrentEnv                    (JMSessionRef             session);
  278.  
  279. #endif  /* defined(JNI_H) */
  280.  
  281. /*
  282.  * Since JManager calls reutrn jref (JRI Java references)
  283.  * you need to convert between them and JNI references (jobjects) if you're
  284.  * using JNI.  These routines facilitate that conversion.
  285.  */
  286. #if defined(JRI_H) && defined(JNI_H)
  287. EXTERN_API_C( jobject )
  288. JMJRIRefToJNIObject                (JMSessionRef             session,
  289.                                  JNIEnv *                env,
  290.                                  jref                     jriRef);
  291.  
  292. EXTERN_API_C( jref )
  293. JMJNIObjectToJRIRef                (JMSessionRef             session,
  294.                                  JNIEnv *                env,
  295.                                  jobject                 jniObject);
  296.  
  297. #endif  /* defined(JRI_H) && defined(JNI_H) */
  298.  
  299. /*
  300.  * Java defines system-wide properties that applets can use to make queries about the
  301.  * host system. Many of these properties correspond to defaults provided by "Internet Config."
  302.  * JMPutSessionProperty can be used by a client program to modify various system-wide properties.
  303.  */
  304. EXTERN_API_C( OSStatus )
  305. JMGetSessionProperty            (JMSessionRef             session,
  306.                                  JMTextRef                 propertyName,
  307.                                  JMTextRef *            propertyValue);
  308.  
  309. EXTERN_API_C( OSStatus )
  310. JMPutSessionProperty            (JMSessionRef             session,
  311.                                  JMTextRef                 propertyName,
  312.                                  JMTextRef                 propertyValue);
  313.  
  314.  
  315. /*
  316.  * Returns a com.apple.mrj.JManager.JMSession object
  317.  */
  318. #ifdef JRI_H
  319. EXTERN_API_C( jref )
  320. JMGetSessionObject                (JMSessionRef             session);
  321.  
  322. #endif  /* defined(JRI_H) */
  323.  
  324. /*
  325.  * JMText: opaque object that encapsulates a string, length, and
  326.  * character encoding.  Strings passed between JManager and the
  327.  * embedding application goes through this interface.  Only the most
  328.  * rudimentary conversion routines are supplied - it is expected that
  329.  * the embedding application will most of its work in the System Script.
  330.  *
  331.  * These APIs present some questions about who actually owns the 
  332.  * JMText.  The rule is, if you created a JMTextRef, you are responsible
  333.  * for deleting it after passing it into the runtime.  If the runtime passes
  334.  * one to you, it will be deleted after the callback.
  335.  *
  336.  * If a pointer to an uninitialised JMTextRef is passed in to a routine (eg JMGetSessionProperty),
  337.  * it is assumed to have been created for the caller, and it is the callers responsibility to
  338.  * dispose of it.
  339.  *
  340.  * The encoding types are taken verbatim from the Text Encoding Converter,
  341.  * which handles the ugly backside of script conversion.
  342.  */
  343. /*
  344.  * JMNewTextRef can create from a buffer of data in the specified encoding
  345.  */
  346. EXTERN_API_C( OSStatus )
  347. JMNewTextRef                    (JMSessionRef             session,
  348.                                  JMTextRef *            textRef,
  349.                                  JMTextEncoding         encoding,
  350.                                  const void *            charBuffer,
  351.                                  UInt32                 bufferLengthInBytes);
  352.  
  353.  
  354. /*
  355.  * JMCopyTextRef clones a text ref.
  356.  */
  357. EXTERN_API_C( OSStatus )
  358. JMCopyTextRef                    (JMTextRef                 textRefSrc,
  359.                                  JMTextRef *            textRefDst);
  360.  
  361.  
  362. /*
  363.  * Disposes of a text ref passed back from the runtime, or created explicitly through JMNewTextRef
  364.  */
  365. EXTERN_API_C( OSStatus )
  366. JMDisposeTextRef                (JMTextRef                 textRef);
  367.  
  368.  
  369. /*
  370.  * Returns the text length, in characters
  371.  */
  372. EXTERN_API_C( OSStatus )
  373. JMGetTextLength                    (JMTextRef                 textRef,
  374.                                  UInt32 *                textLengthInCharacters);
  375.  
  376.  
  377. /*
  378.  * Returns the text length, in number of bytes taken in the destination encoding
  379.  */
  380. EXTERN_API_C( OSStatus )
  381. JMGetTextLengthInBytes            (JMTextRef                 textRef,
  382.                                  JMTextEncoding         dstEncoding,
  383.                                  UInt32 *                textLengthInBytes);
  384.  
  385.  
  386. /*
  387.  * Copies the specified number of characters to the destination buffer with the appropriate
  388.  * destination encoding.
  389.  */
  390. EXTERN_API_C( OSStatus )
  391. JMGetTextBytes                    (JMTextRef                 textRef,
  392.                                  JMTextEncoding         dstEncoding,
  393.                                  void *                    textBuffer,
  394.                                  UInt32                 textBufferLength,
  395.                                  UInt32 *                numCharsCopied);
  396.  
  397.  
  398. /*
  399.  * Return the JMText as a reference to a Java String.  Note that
  400.  * this is the only reference to the string - it will be collected if you don't
  401.  * hang on to it.
  402.  */
  403. #ifdef JRI_H
  404. EXTERN_API_C( jref )
  405. JMTextToJavaString                (JMTextRef                 textRef);
  406.  
  407. #endif  /* defined(JRI_H) */
  408.  
  409. /*
  410.  * Returns a Handle to a null terminated, "C" string in the System Script.
  411.  */
  412. EXTERN_API_C( Handle )
  413. JMTextToMacOSCStringHandle        (JMTextRef                 textRef);
  414.  
  415.  
  416.  
  417.  
  418. /*
  419.  * Proxy properties in the runtime.
  420.  *
  421.  * These will only be checked if InternetConfig isn't used to specify properties,
  422.  * or if it doesn't have the data for these.
  423.  */
  424.  
  425. struct JMProxyInfo {
  426.     Boolean                         useProxy;
  427.     char                             proxyHost[255];
  428.     UInt16                             proxyPort;
  429. };
  430. typedef struct JMProxyInfo                JMProxyInfo;
  431.  
  432. enum JMProxyType {
  433.     eHTTPProxy                    = 0,
  434.     eFirewallProxy                = 1,
  435.     eFTPProxy                    = 2
  436. };
  437. typedef enum JMProxyType JMProxyType;
  438.  
  439. EXTERN_API_C( OSStatus )
  440. JMGetProxyInfo                    (JMSessionRef             session,
  441.                                  JMProxyType             proxyType,
  442.                                  JMProxyInfo *            proxyInfo);
  443.  
  444. EXTERN_API_C( OSStatus )
  445. JMSetProxyInfo                    (JMSessionRef             session,
  446.                                  JMProxyType             proxyType,
  447.                                  const JMProxyInfo *    proxyInfo);
  448.  
  449.  
  450. /*
  451.  * Security - JManager 2.0 security is handled on a per-applet basis.
  452.  * There are some security settings that are inherited from InternetConfig
  453.  * (Proxy Servers) but the verifier can now be enabled and disabled.
  454.  */
  455. EXTERN_API_C( OSStatus )
  456. JMGetVerifyMode                    (JMSessionRef             session,
  457.                                  JMVerifierOptions *    verifierOptions);
  458.  
  459. EXTERN_API_C( OSStatus )
  460. JMSetVerifyMode                    (JMSessionRef             session,
  461.                                  JMVerifierOptions         verifierOptions);
  462.  
  463.  
  464.  
  465.  
  466. /*
  467.  * The basic unit of AWT interaction is the JMFrame.  A JMFrame is bound to top level
  468.  * awt Frame, Window, or Dialog.  When a user event occurs for a MacOS window, the event is passed
  469.  * to the corrosponding frame object.  Similarly, when an AWT event occurs that requires the
  470.  * Mac OS Window to change, a callback is made.  JManager 1.x bound the frame to the window through
  471.  * a callback to set and restore the windows GrafPort.  In JManager 2.0, a GrafPort, Offset, and 
  472.  * ClipRgn are specified up front - changes in visibility and structure require that these be re-set.
  473.  * This enables support for the JavaSoft DrawingSurface API - and also improves graphics performance.
  474.  * You should reset the graphics attributes anytime the visiblity changes, like when scrolling.
  475.  * You should also set it initially when the AWTContext requests the frame.
  476.  * At various times, JM will call back to the client to register a new JMFrame, 
  477.  * indicating the frame type.  The client should take the following steps:
  478.  *
  479.  *    o    Create a new invisible window of the specified type
  480.  *    o    Fill in the callbacks parameter with function pointers
  481.  *    o    Do something to bind the frame to the window (like stuff the WindowPtr in the JMClientData of the frame)
  482.  *    o    Register the visiblity parameters (GrafPtr, etc) with the frame
  483.  */
  484.  
  485. enum ReorderRequest {
  486.     eBringToFront                = 0,                            /* bring the window to front */
  487.     eSendToBack                    = 1,                            /* send the window to back */
  488.     eSendBehindFront            = 2                                /* send the window behind the front window */
  489. };
  490. typedef enum ReorderRequest ReorderRequest;
  491.  
  492. typedef CALLBACK_API_C( void , JMSetFrameSizeProcPtr )(JMFrameRef frame, const Rect *newBounds);
  493. typedef CALLBACK_API_C( void , JMFrameInvalRectProcPtr )(JMFrameRef frame, const Rect *r);
  494. typedef CALLBACK_API_C( void , JMFrameShowHideProcPtr )(JMFrameRef frame, Boolean showFrameRequested);
  495. typedef CALLBACK_API_C( void , JMSetTitleProcPtr )(JMFrameRef frame, JMTextRef title);
  496. typedef CALLBACK_API_C( void , JMCheckUpdateProcPtr )(JMFrameRef frame);
  497. typedef CALLBACK_API_C( void , JMReorderFrame )(JMFrameRef frame, ReorderRequest theRequest);
  498. typedef CALLBACK_API_C( void , JMSetResizeable )(JMFrameRef frame, Boolean resizeable);
  499.  
  500. struct JMFrameCallbacks {
  501.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  502.     JMSetFrameSizeProcPtr             fSetFrameSize;
  503.     JMFrameInvalRectProcPtr         fInvalRect;
  504.     JMFrameShowHideProcPtr             fShowHide;
  505.     JMSetTitleProcPtr                 fSetTitle;
  506.     JMCheckUpdateProcPtr             fCheckUpdate;
  507.     JMReorderFrame                     fReorderFrame;
  508.     JMSetResizeable                 fSetResizeable;
  509. };
  510. typedef struct JMFrameCallbacks            JMFrameCallbacks;
  511. EXTERN_API_C( OSStatus )
  512. JMSetFrameVisibility            (JMFrameRef             frame,
  513.                                  GrafPtr                 famePort,
  514.                                  Point                     frameOrigin,
  515.                                  RgnHandle                 frameClip);
  516.  
  517. EXTERN_API_C( OSStatus )
  518. JMGetFrameData                    (JMFrameRef             frame,
  519.                                  JMClientData *            data);
  520.  
  521. EXTERN_API_C( OSStatus )
  522. JMSetFrameData                    (JMFrameRef             frame,
  523.                                  JMClientData             data);
  524.  
  525. EXTERN_API_C( OSStatus )
  526. JMGetFrameSize                    (JMFrameRef             frame,
  527.                                  Rect *                    result);
  528.  
  529. /* note that the top left indicates the "global" position of this frame */
  530. /* use this to update the frame position when it gets moved */
  531. EXTERN_API_C( OSStatus )
  532. JMSetFrameSize                    (JMFrameRef             frame,
  533.                                  const Rect *            newSize);
  534.  
  535. /*
  536.  * Dispatch a particular event to an embedded frame
  537.  */
  538. EXTERN_API_C( OSStatus )
  539. JMFrameClick                    (JMFrameRef             frame,
  540.                                  Point                     localPos,
  541.                                  short                     modifiers);
  542.  
  543. EXTERN_API_C( OSStatus )
  544. JMFrameKey                        (JMFrameRef             frame,
  545.                                  char                     asciiChar,
  546.                                  char                     keyCode,
  547.                                  short                     modifiers);
  548.  
  549. EXTERN_API_C( OSStatus )
  550. JMFrameKeyRelease                (JMFrameRef             frame,
  551.                                  char                     asciiChar,
  552.                                  char                     keyCode,
  553.                                  short                     modifiers);
  554.  
  555. EXTERN_API_C( OSStatus )
  556. JMFrameUpdate                    (JMFrameRef             frame,
  557.                                  RgnHandle                 updateRgn);
  558.  
  559. EXTERN_API_C( OSStatus )
  560. JMFrameActivate                    (JMFrameRef             frame,
  561.                                  Boolean                 activate);
  562.  
  563. EXTERN_API_C( OSStatus )
  564. JMFrameResume                    (JMFrameRef             frame,
  565.                                  Boolean                 resume);
  566.  
  567. EXTERN_API_C( OSStatus )
  568. JMFrameMouseOver                (JMFrameRef             frame,
  569.                                  Point                     localPos,
  570.                                  short                     modifiers);
  571.  
  572. EXTERN_API_C( OSStatus )
  573. JMFrameShowHide                    (JMFrameRef             frame,
  574.                                  Boolean                 showFrame);
  575.  
  576. EXTERN_API_C( OSStatus )
  577. JMFrameGoAway                    (JMFrameRef             frame);
  578.  
  579. EXTERN_API_C( JMAWTContextRef )
  580. JMGetFrameContext                (JMFrameRef             frame);
  581.  
  582. EXTERN_API_C( OSStatus )
  583. JMFrameDragTracking                (JMFrameRef             frame,
  584.                                  DragTrackingMessage     message,
  585.                                  DragReference             theDragRef);
  586.  
  587. EXTERN_API_C( OSStatus )
  588. JMFrameDragReceive                (JMFrameRef             frame,
  589.                                  DragReference             theDragRef);
  590.  
  591. #ifdef JRI_H
  592. /* 
  593.  * returns the java.awt.Frame for this frame 
  594. */
  595. EXTERN_API_C( jref )
  596. JMGetAWTFrameObject                (JMFrameRef             frame);
  597.  
  598. /* 
  599.  * returns the com.apple.mrj.JManager.JMFrame for this frame 
  600.  */
  601. EXTERN_API_C( jref )
  602. JMGetJMFrameObject                (JMFrameRef             frame);
  603.  
  604. #endif  /* defined(JRI_H) */
  605.  
  606. /*
  607.  * Window types
  608.  */
  609.  
  610. enum JMFrameKind {
  611.     eBorderlessModelessWindowFrame = 0,
  612.     eModelessWindowFrame        = 1,
  613.     eModalWindowFrame            = 2,
  614.     eModelessDialogFrame        = 3
  615. };
  616. typedef enum JMFrameKind JMFrameKind;
  617.  
  618.  
  619.  
  620.  
  621. /* JMAWTContext -
  622.  * To create a top level frame, you must use a JMAWTContext object.
  623.  * The JMAWTContext provides a context for the AWT to request frames.
  624.  * A AWTContext has a threadgroup associated with it - all events and processing occurs
  625.  * there.  When you create one, it is quiescent, you must call resume before it begins executing.
  626.  */
  627. typedef CALLBACK_API_C( OSStatus , JMRequestFrameProcPtr )(JMAWTContextRef context, JMFrameRef newFrame, JMFrameKind kind, const Rect *initialBounds, Boolean resizeable, JMFrameCallbacks *callbacks);
  628. typedef CALLBACK_API_C( OSStatus , JMReleaseFrameProcPtr )(JMAWTContextRef context, JMFrameRef oldFrame);
  629. typedef CALLBACK_API_C( SInt16 , JMUniqueMenuIDProcPtr )(JMAWTContextRef context, Boolean isSubmenu);
  630. typedef CALLBACK_API_C( void , JMExceptionOccurredProcPtr )(JMAWTContextRef context, JMTextRef exceptionName, JMTextRef exceptionMsg, JMTextRef stackTrace);
  631.  
  632. struct JMAWTContextCallbacks {
  633.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  634.     JMRequestFrameProcPtr             fRequestFrame;                /* a new frame is being created. */
  635.     JMReleaseFrameProcPtr             fReleaseFrame;                /* an existing frame is being destroyed. */
  636.     JMUniqueMenuIDProcPtr             fUniqueMenuID;                /* a new menu will be created with this id. */
  637.     JMExceptionOccurredProcPtr         fExceptionOccurred;            /* just some notification that some recent operation caused an exception.  You can't do anything really from here. */
  638. };
  639. typedef struct JMAWTContextCallbacks    JMAWTContextCallbacks;
  640. EXTERN_API_C( OSStatus )
  641. JMNewAWTContext                    (JMAWTContextRef *        context,
  642.                                  JMSessionRef             session,
  643.                                  const JMAWTContextCallbacks * callbacks,
  644.                                  JMClientData             data);
  645.  
  646. EXTERN_API_C( OSStatus )
  647. JMDisposeAWTContext                (JMAWTContextRef         context);
  648.  
  649. EXTERN_API_C( OSStatus )
  650. JMGetAWTContextData                (JMAWTContextRef         context,
  651.                                  JMClientData *            data);
  652.  
  653. EXTERN_API_C( OSStatus )
  654. JMSetAWTContextData                (JMAWTContextRef         context,
  655.                                  JMClientData             data);
  656.  
  657. EXTERN_API_C( OSStatus )
  658. JMCountAWTContextFrames            (JMAWTContextRef         context,
  659.                                  UInt32 *                frameCount);
  660.  
  661. EXTERN_API_C( OSStatus )
  662. JMGetAWTContextFrame            (JMAWTContextRef         context,
  663.                                  UInt32                 frameIndex,
  664.                                  JMFrameRef *            frame);
  665.  
  666. EXTERN_API_C( OSStatus )
  667. JMMenuSelected                    (JMAWTContextRef         context,
  668.                                  MenuHandle             hMenu,
  669.                                  short                     menuItem);
  670.  
  671. #ifdef JRI_H
  672. /*
  673.  * JRI Access APIs
  674.  */
  675. EXTERN_API_C( OSStatus )
  676. JMExecMethodInContext            (JMAWTContextRef         context,
  677.                                  jref                     objref,
  678.                                  JRIMethodID             methodID,
  679.                                  UInt32                 argCount,
  680.                                  JRIValue                 args[]);
  681.  
  682. EXTERN_API_C( OSStatus )
  683. JMExecStaticMethodInContext        (JMAWTContextRef         context,
  684.                                  JRIClassID             classID,
  685.                                  JRIMethodID             methodID,
  686.                                  UInt32                 argCount,
  687.                                  JRIValue                 args[]);
  688.  
  689. #endif  /* defined(JRI_H) */
  690.  
  691. #ifdef JNI_H
  692. /*
  693.  * JNI Access APIs
  694.  * Note that you must pass the JNIEnv to these as well.
  695.  */
  696. EXTERN_API_C( OSStatus )
  697. JMExecJNIMethodInContext        (JMAWTContextRef         context,
  698.                                  JNIEnv *                env,
  699.                                  jobject                 objref,
  700.                                  jmethodID                 methodID,
  701.                                  UInt32                 argCount,
  702.                                  jvalue                 args[]);
  703.  
  704. EXTERN_API_C( OSStatus )
  705. JMExecJNIStaticMethodInContext    (JMAWTContextRef         context,
  706.                                  JNIEnv *                env,
  707.                                  jclass                 classID,
  708.                                  jmethodID                 methodID,
  709.                                  UInt32                 argCount,
  710.                                  jvalue                 args[]);
  711.  
  712. /*
  713.  * return a com.apple.jmanager.AWTContext
  714.  */
  715. EXTERN_API_C( jref )
  716. JMGetAwtContextObject            (JMAWTContextRef         context);
  717.  
  718. #endif  /* defined(JNI_H) */
  719.  
  720.  
  721.  
  722.  
  723. /*
  724.  * JMAppletLocator - Since Java applets are always referenced by a Uniform Resource Locator
  725.  * (see RFC 1737, http://www.w3.org/pub/WWW/Addressing/rfc1738.txt), we provide an object
  726.  * that encapsulates the information about a set of applets. A JMAppletLocator is built
  727.  * by providing a base URL, which must point at a valid HTML document containing applet
  728.  * tags. To save a network transaction, the contents of the document may be passed optionally. 
  729.  *
  730.  * You can also use a JMLocatorInfoBlock for a synchronous resolution of the applet,
  731.  * assuming that you already have the info for the tag.
  732.  */
  733.  
  734. enum JMLocatorErrors {
  735.     eLocatorNoErr                = 0,                            /* the html was retrieved successfully*/
  736.     eHostNotFound                = 1,                            /* the host specified by the url could not be found*/
  737.     eFileNotFound                = 2,                            /* the file could not be found on the host*/
  738.     eLocatorTimeout                = 3,                            /* a timeout occurred retrieving the html text*/
  739.     eLocatorKilled                = 4                                /* in response to a JMDisposeAppletLocator before it has completed*/
  740. };
  741. typedef enum JMLocatorErrors JMLocatorErrors;
  742.  
  743. typedef CALLBACK_API_C( void , JMFetchCompleted )(JMAppletLocatorRef ref, JMLocatorErrors status);
  744.  
  745. struct JMAppletLocatorCallbacks {
  746.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  747.     JMFetchCompleted                 fCompleted;                    /* called when the html has been completely fetched */
  748. };
  749. typedef struct JMAppletLocatorCallbacks    JMAppletLocatorCallbacks;
  750. /*
  751.  * These structures are used to pass pre-parsed parameter
  752.  * tags to the AppletLocator.  Implies synchronous semantics.
  753.  */
  754.  
  755.  
  756. struct JMLIBOptionalParams {
  757.     JMTextRef                         fParamName;                    /* could be from a <parameter name=foo value=bar> or "zipbase", etc */
  758.     JMTextRef                         fParamValue;                /* the value of this optional tag */
  759. };
  760. typedef struct JMLIBOptionalParams        JMLIBOptionalParams;
  761.  
  762. struct JMLocatorInfoBlock {
  763.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  764.  
  765.                                                                 /* These are required to be present and not nil */
  766.  
  767.     JMTextRef                         fBaseURL;                    /* the URL of this applet's host page */
  768.     JMTextRef                         fAppletCode;                /* code= parameter */
  769.     short                             fWidth;                        /* width= parameter */
  770.     short                             fHeight;                    /* height= parameter */
  771.  
  772.  
  773.                                                                 /* These are optional parameters */
  774.     SInt32                             fOptionalParameterCount;    /* how many in this array */
  775.     JMLIBOptionalParams *            fParams;                    /* pointer to an array of these (points to first element) */
  776. };
  777. typedef struct JMLocatorInfoBlock        JMLocatorInfoBlock;
  778. EXTERN_API_C( OSStatus )
  779. JMNewAppletLocator                (JMAppletLocatorRef *    locatorRef,
  780.                                  JMSessionRef             session,
  781.                                  const JMAppletLocatorCallbacks * callbacks,
  782.                                  JMTextRef                 url,
  783.                                  JMTextRef                 htmlText,
  784.                                  JMClientData             data);
  785.  
  786. EXTERN_API_C( OSStatus )
  787. JMNewAppletLocatorFromInfo        (JMAppletLocatorRef *    locatorRef,
  788.                                  JMSessionRef             session,
  789.                                  const JMLocatorInfoBlock * info,
  790.                                  JMClientData             data);
  791.  
  792. EXTERN_API_C( OSStatus )
  793. JMDisposeAppletLocator            (JMAppletLocatorRef     locatorRef);
  794.  
  795. EXTERN_API_C( OSStatus )
  796. JMGetAppletLocatorData            (JMAppletLocatorRef     locatorRef,
  797.                                  JMClientData *            data);
  798.  
  799. EXTERN_API_C( OSStatus )
  800. JMSetAppletLocatorData            (JMAppletLocatorRef     locatorRef,
  801.                                  JMClientData             data);
  802.  
  803. EXTERN_API_C( OSStatus )
  804. JMCountApplets                    (JMAppletLocatorRef     locatorRef,
  805.                                  UInt32 *                appletCount);
  806.  
  807. EXTERN_API_C( OSStatus )
  808. JMGetAppletDimensions            (JMAppletLocatorRef     locatorRef,
  809.                                  UInt32                 appletIndex,
  810.                                  UInt32 *                width,
  811.                                  UInt32 *                height);
  812.  
  813. EXTERN_API_C( OSStatus )
  814. JMGetAppletTag                    (JMAppletLocatorRef     locatorRef,
  815.                                  UInt32                 appletIndex,
  816.                                  JMTextRef *            tagRef);
  817.  
  818. EXTERN_API_C( OSStatus )
  819. JMGetAppletName                    (JMAppletLocatorRef     locatorRef,
  820.                                  UInt32                 appletIndex,
  821.                                  JMTextRef *            nameRef);
  822.  
  823.  
  824. /*
  825.  * JMAppletViewer - Applets are instantiated, one by one, by specifying a JMAppletLocator and
  826.  * a zero-based index (Macintosh API's usually use one-based indexing, the Java language
  827.  * uses zero, however.). The resulting applet is encapsulated in a JMAppletViewer object. 
  828.  * Since applets can have one or more visible areas to draw in, one or more JMFrame objects
  829.  * may be requested while the viewer is being created, or at a later time, thus the client
  830.  * must provide callbacks to satisfy these requests.
  831.  *
  832.  * The window name for the ShowDocument callback is one of:
  833.  *   _self        show in current frame
  834.  *   _parent    show in parent frame
  835.  *   _top        show in top-most frame
  836.  *   _blank        show in new unnamed top-level window
  837.  *   <other>    show in new top-level window named <other> 
  838.  */
  839. typedef CALLBACK_API_C( void , JMShowDocumentProcPtr )(JMAppletViewerRef viewer, JMTextRef urlString, JMTextRef windowName);
  840. typedef CALLBACK_API_C( void , JMSetStatusMsgProcPtr )(JMAppletViewerRef viewer, JMTextRef statusMsg);
  841.  
  842. struct JMAppletViewerCallbacks {
  843.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  844.     JMShowDocumentProcPtr             fShowDocument;                /* go to a url, optionally in a new window */
  845.     JMSetStatusMsgProcPtr             fSetStatusMsg;                /* applet changed status message */
  846. };
  847. typedef struct JMAppletViewerCallbacks    JMAppletViewerCallbacks;
  848. /*
  849.  * NEW: per-applet security settings
  850.  * Previously, these settings were attached to the session.
  851.  * JManager 2.0 allows them to be attached to each viewer.
  852.  */
  853.  
  854. enum JMNetworkSecurityOptions {
  855.     eNoNetworkAccess            = 0,
  856.     eAppletHostAccess            = 1,
  857.     eUnrestrictedAccess            = 2
  858. };
  859. typedef enum JMNetworkSecurityOptions JMNetworkSecurityOptions;
  860.  
  861.  
  862. enum JMFileSystemOptions {
  863.     eNoFSAccess                    = 0,
  864.     eLocalAppletAccess            = 1,
  865.     eAllFSAccess                = 2
  866. };
  867. typedef enum JMFileSystemOptions JMFileSystemOptions;
  868.  
  869. /*
  870.  * Lists of packages are comma separated,
  871.  * the default for mrj.security.system.access is
  872.  * "sun,netscape,com.apple".
  873.  */
  874.  
  875.  
  876. struct JMAppletSecurity {
  877.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  878.     JMNetworkSecurityOptions         fNetworkSecurity;            /* can this applet access network resources */
  879.     JMFileSystemOptions             fFileSystemSecurity;        /* can this applet access network resources */
  880.  
  881.     Boolean                         fRestrictSystemAccess;        /* restrict access to system packages (com.apple.*, sun.*, netscape.*) also found in the property "mrj.security.system.access" */
  882.     Boolean                         fRestrictSystemDefine;        /* restrict classes from loading system packages (com.apple.*, sun.*, netscape.*) also found in the property "mrj.security.system.define" */
  883.  
  884.     Boolean                         fRestrictApplicationAccess;    /* restrict access to application packages found in the property "mrj.security.application.access" */
  885.     Boolean                         fRestrictApplicationDefine;    /* restrict access to application packages found in the property "mrj.security.application.access" */
  886. };
  887. typedef struct JMAppletSecurity            JMAppletSecurity;
  888. /*
  889.  * AppletViewer methods
  890.  */
  891. EXTERN_API_C( OSStatus )
  892. JMNewAppletViewer                (JMAppletViewerRef *    viewer,
  893.                                  JMAWTContextRef         context,
  894.                                  JMAppletLocatorRef     locatorRef,
  895.                                  UInt32                 appletIndex,
  896.                                  const JMAppletSecurity * security,
  897.                                  const JMAppletViewerCallbacks * callbacks,
  898.                                  JMClientData             data);
  899.  
  900. EXTERN_API_C( OSStatus )
  901. JMDisposeAppletViewer            (JMAppletViewerRef         viewer);
  902.  
  903. EXTERN_API_C( OSStatus )
  904. JMGetAppletViewerData            (JMAppletViewerRef         viewer,
  905.                                  JMClientData *            data);
  906.  
  907. EXTERN_API_C( OSStatus )
  908. JMSetAppletViewerData            (JMAppletViewerRef         viewer,
  909.                                  JMClientData             data);
  910.  
  911.  
  912. /*
  913.  * You can change the applet security on the fly
  914.  */
  915. EXTERN_API_C( OSStatus )
  916. JMGetAppletViewerSecurity        (JMAppletViewerRef         viewer,
  917.                                  JMAppletSecurity *        data);
  918.  
  919. EXTERN_API_C( OSStatus )
  920. JMSetAppletViewerSecurity        (JMAppletViewerRef         viewer,
  921.                                  const JMAppletSecurity * data);
  922.  
  923.  
  924. /*
  925.  * JMReloadApplet reloads viewer's applet from the source.
  926.  * JMRestartApplet reinstantiates the applet without reloading.
  927.  */
  928. EXTERN_API_C( OSStatus )
  929. JMReloadApplet                    (JMAppletViewerRef         viewer);
  930.  
  931. EXTERN_API_C( OSStatus )
  932. JMRestartApplet                    (JMAppletViewerRef         viewer);
  933.  
  934.  
  935. /*
  936.  * JMSuspendApplet tells the Java thread scheduler to stop executing the viewer's applet.
  937.  * JMResumeApplet resumes execution of the viewer's applet.
  938.  */
  939. EXTERN_API_C( OSStatus )
  940. JMSuspendApplet                    (JMAppletViewerRef         viewer);
  941.  
  942. EXTERN_API_C( OSStatus )
  943. JMResumeApplet                    (JMAppletViewerRef         viewer);
  944.  
  945.  
  946. /* 
  947.  * To get back to the JMAppletViewerRef instance from whence a frame came,
  948.  * as well as the ultimate frame parent (the one created _for_ the applet viewer)
  949.  */
  950. EXTERN_API_C( OSStatus )
  951. JMGetFrameViewer                (JMFrameRef             frame,
  952.                                  JMAppletViewerRef *    viewer,
  953.                                  JMFrameRef *            parentFrame);
  954.  
  955. /*
  956.  * To get a ref back to the Frame that was created for this JMAppletViewerRef
  957.  */
  958. EXTERN_API_C( OSStatus )
  959. JMGetViewerFrame                (JMAppletViewerRef         viewer,
  960.                                  JMFrameRef *            frame);
  961.  
  962. #ifdef JRI_H
  963. /*
  964.  * To get the ref of the com.apple.mrj.JManager.JMAppletViewer java object
  965.  */
  966. EXTERN_API_C( jref )
  967. JMGetAppletViewerObject            (JMAppletViewerRef         viewer);
  968.  
  969. /*
  970.  * To get the ref of the java.applet.Applet itself
  971.  */
  972. EXTERN_API_C( jref )
  973. JMGetAppletObject                (JMAppletViewerRef         viewer);
  974.  
  975. #endif  /* defined(JRI_H) */
  976.  
  977.  
  978. #if PRAGMA_ENUM_ALWAYSINT
  979.     #pragma enumsalwaysint reset
  980. #elif PRAGMA_ENUM_OPTIONS
  981.     #pragma option enum=reset
  982. #elif defined(PRAGMA_ENUM_PACK__JMANAGER__)
  983.     #pragma options(pack_enums)
  984. #endif
  985.  
  986. #if PRAGMA_STRUCT_ALIGN
  987.     #pragma options align=reset
  988. #elif PRAGMA_STRUCT_PACKPUSH
  989.     #pragma pack(pop)
  990. #elif PRAGMA_STRUCT_PACK
  991.     #pragma pack()
  992. #endif
  993.  
  994. #ifdef PRAGMA_IMPORT_OFF
  995. #pragma import off
  996. #elif PRAGMA_IMPORT
  997. #pragma import reset
  998. #endif
  999.  
  1000. #ifdef __cplusplus
  1001. }
  1002. #endif
  1003.  
  1004. #endif /* __JMANAGER__ */
  1005.  
  1006.